/**
 * \file    doc/building.h
 * \brief   Documentation: How to build WOSH Framework
 ****************************************************************************
 * @author  Alessandro Polo
 * @version 0.8.499 $Id: building.h 2861 2010-08-07 02:42:53Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2010, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/

/*! \page page_build Building
 *
 * This page explains how to compile and build WOSH on your system.
 *
 * \section page_build_toc Table of Contents:
 *
 *  - \ref page_build_overview
 *  - \ref page_build_req
 *  - \ref page_build_arch
 *  - \ref page_build_3rdparty
 *
 *  - \ref page_build_compile_posix
 *  - \ref page_build_compile_win32
 *  - \ref page_build_compile_win32_mingw
 *  - \ref page_build_compile_wince
 *  - \ref page_build_compile_macos
 *
 *  - \ref page_build_doc
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_overview Overview
 *
 * WOSH is a modular framework, building a WOSH application means satisfying
 * requirements at different levels:
 *  - WOSH Core - Core library (kernel, modules and core-components) is always included 
 *    in any WOSH application, so all of its requirements must be fulfilled.
 *  - WOSH Framework - Depending on the application and included services
 *    a part of (or the whole) framework library must be built.
 *  - WOSH Application - Finally application-scope's explicit references
 *    to external libraries must be linked.
 *
 * Almost all components (but not wosh::Thread yet) of WOSH Core library (source in
 * the /src/core folder) is written in pure ANSI C++ (using STL)
 * and does NOT require any external library.
 *
 * Some namespaces of the WOSH Framework are actually based on QT4 or grater. (Network, Persistence)
 *
 * WOSH links only to stable, state-of-the-art libraries.
 *
 * Actually, WOSH Core and Framework are compiled within same built, that means
 * you have to supply all required libraries, see next section for listing.
 *
 * In short, for a standard/minimal built, you will need QT4 or greater.
 *
 * \note From WOSH 0.8.013 [icarus]
 *  I started the (long) process of making WOSH even more scalable, introducing
 *  support of more optional libraries. WOSH Applications with a GUI interface will always
 *  be based on QT (as the WOSH GUI framework), but I plan to reduce requirements
 *  of the rest of the framework and WOSH Core itself.
 *  Actually there are few (but important) topics where QT comes in help:
 *   - Threading (but started the implementation of Mutex and pthread-based Thread),
 *   - Networking (but started the support for libSocket library, UDP socket is released),
 *   - XML serialization.
 *
 * Finally, note that built-in services add requirements to the application.
 * For example, adding wosh::devices::JabberGlooxBundle will force
 * the application to link the \c libgloox library (which is available freely and
 * it's multi-platform, but should be installed properly).
 * In some cases, this type of dependencies will produce a platform-specific application.
 *
 * In short, requirements of a WOSH application are the sum of its components'
 * requirements. See \ref page_debug_libs for more information about linking 
 * shared and 3rd-party libraries, the section prompts also an example of how many libs
 * are required by a complex \c woshsrv application built for Linux Debian
 * (don't be scared by the number of libraries, most of them are included in
 * the Linux distributions by default, others may be easily installed).
 *
 * \note For developers:
 *  It is suggested to have a different working copy for each platform, this
 *  will avoid many issues about generated output and temporary files.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_req Platforms, Compilers and Required tools
 *
 * WOSH is written in ANSI C++ (ISO/IEC 14882:2003), (partially) based
 * on QT framework and compatible with following platforms:
 *  - POSIX [native] (Linux/UNIX systems)
 *  - Windows [native] (2000, XP, CE6.0, Mobile 6.0)
 *  - Windows [ported-mingw] (some core files must be updated, actually not supported)
 *  - Window Vista (not tested! but will work)
 *  - MAC OS (not tested! but should work)
 *
 * \par Compilers and Libraries
 * Any ANSI C++ compatible compiler should work (GCC, MSC, MinGW GCC, ..),
 * STL (Standard Template Library) must be available as well (and it always is, just don't care).
 *
 * <a href="http://qt.nokia.com/products">Nokia QT library</a> (and headers) must be properly installed and configured.
 * WOSH Core and Framework require QT 4.1 or later, some applications (such as
 * WoshShop and KiosK) require QT 4.5 or later.
 *
 * WOSH has been developed and tested on following OS:
 *  - \ref page_build_compile_posix "POSIX (Linux)"
 *    - Linux Debian Etch (4.0) - GCC 4:4.1.1-15
 *    - Linux Debian Lenny (5.0) - GCC 4.3.2-1.1
 *    - Linux Ubuntu 9.x - GCC 4:4.3.3-1
 *  - \ref page_build_compile_win32 "Windows"
 *    - Windows 2000 Professional (SP2) - Microsoft Visual Studio C++ 2008
 *    - Windows XP (SP3) - Microsoft Visual Studio C++ 2008 [Microsoft 32-bit C/C++ Optimizing Compiler Version 15.00.30729.01 for 80x86]
 *  - \ref page_build_compile_wince "Windows Mobile" 6.x - Microsoft Visual Studio C++ 2008 with Windows Mobile 6 Standard SDK [cross-compiled ARMV4I]
 *
 * You may find some instructions and tips further within each OS-specific section.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_arch Architecture and Configuration
 * 
 * Build process is organized using QT Project makefiles (.pro), \c qmake tool will generate
 * the appropriate makefile on each platform. You may find more information about
 * <a href="http://doc.trolltech.com/qmake-manual.html">QMake on QT documentation</a>.
 *
 * \note The building model is planned to be changed in the future release WOSH QED [1.x],
 *       in order to standardize the process (probably using GNU \c autotools).
 *
 * The build is hierarchical, project files are included recursively and always refers to /src folder.
 * Usually, all source folders contain a \c .pro  or \c .prf project file, which may be included
 * by its parent directory (depending on settings). By Qmake point of view, commands will be directly
 * included (so paths must always refer to \c /src as root folder).
 *
 * Almost all WOSH applications' project files share many common directives and source files,
 * because of that, they include <a href="../../src/common.pri">common.pri</a> project file.
 *
 * This shared configuration forces many settings, such as:
 *  - include WOSH Core (<a href="../../src/core/core.pro">/src/core/core.pro</a>)
 *  - include WOSH Interfaces (<a href="../../src/interfaces/interfaces.pro">/src/interfaces/interfaces.pro</a>)
 *  - Makefile are generated in <a href="../../src">/src</a> folder,
 *  - binaries are written in <a href="../../bin">/bin</a> folder,
 *  - temporary files are saved in \c tmp fodler (and sub-folders).
 *  - include <a href="../../lib/3rdparty">/lib/3rdparty</a> folder, \c /usr/lib on POSIX
 *  - setup some required preprocessor defines such as \c _OS_POSIX, \c _OS_WIN32, \c _OS_WINCE
 *    (this is very important, else it will raise a bunch of compilation errors)
 *  - QT GUI module is disabled (when the WOSH GUI framework is include it will be enabled by its own project file)
 *  - eventually (if exists) include \c custom.pri, after default configuration (so you may override it)
 *    you shouldn't (ever need to) change project files under version control, to customize the build
 *    create/edit and the custom.pri file.
 *
 * Note that WOSH Framework (<a href="../../src/framework/framework.pro">/src/framework/framework.pro</a>)
 * is not included or properly configured by this shared project-file.
 * It has to be explicitly included in the application's project file.
 *
 * You may give a look to included applications' project-files, always located in <a href="../../src">/src</a> folder:
 *  - <a href="../../src/woshsrv.pro">/src/woshsrv.pro</a> - \ref page_applications_woshsrv
 *  - <a href="../../src/woshshop.pro">/src/woshshop.pro</a> - \ref page_applications_woshshop
 *  - <a href="../../src/woshshop.pro">/src/woshkisk.pro</a> - - \ref page_applications_woshkiosk
 *  - <a href="../../src/woshremote.pro">/src/woshremote.pro</a> - \ref page_applications_woshremote
 *  - <a href="../../src/woshcesrv.pro">/src/woshcesrv.pro</a> - \ref page_applications_woshcesrv
 *  - <a href="../../src/woshlib.pro">/src/woshlib.pro</a> - WOSH Static Library
 *
 * The framework configuration is quite easy, basically you may enable/disable a namespace (sub-library)
 * of the WOSH Framework just (un)commenting a define line, options are:
 * \verbatim
#####################################################
# set namespaces of the WOSH Framework to build-in
#
#CONFIG += WOSH_AI
CONFIG += WOSH_AUTOMATIONS
CONFIG += WOSH_BUILDING
CONFIG += WOSH_COMMUNICATION
CONFIG += WOSH_ENTERTAINMENT
CONFIG += WOSH_GUI
CONFIG += WOSH_PLUGINS
CONFIG += WOSH_SECURITY
CONFIG += WOSH_XTENDED
#####################################################
# include WOSH Framework, framework options must be
# configured before following command.
#
!include( framework/framework.pro ) {
	error( "FATAL: Project file 'framework/framework.pro' is missing! (misaligned distribution?)" )
}
\endverbatim
 * This sample snippet will include the whole framework but \ref page_framework_ai
 *
 * \warning
 *  Only the \b Network and \b Persistence modules of the WOSH framework are actually built-in
 *  by default (because of they are required for distributed computing).
 *
 * Finally we definitely need to include the application's source files (containing \c main entry point):
 * \verbatim
#####################################################
# define application's resources
#
RESOURCES += apps/woshshop/woshshop.qrc
TRANSLATIONS += apps/woshshop/translations/woshshop_it.ts

#####################################################
# include application's core file
#
SOURCES += apps/woshshop/woshshop.cpp
HEADERS += apps/woshshop/WoshShopWindow.h
SOURCES += apps/woshshop/WoshShopWindow.cpp
FORMS   += apps/woshshop/WoshShopWindow.ui
[..]
\endverbatim
 *
 * As you should know, WOSH is a service-oriented system, based on \b Bundles.
 * WOSH applications will probably host a set of services (woshsrv does nothing but this),
 * bundles may be loaded dynamically at run-time (as external library) or be included in the build.
 *
 * \warning Dynamic loading is still experimental, it is suggested to include bundles in the executable.
 *
 * Assuming all requirements (and referenced libraries) of bundles are fulfilled, the selected bundles
 * must be explicitly included in project file.
 *
 * There is a project file also in each bundle's folder, it will include source code and
 * add required libraries (and directives) to the build.
 *
 * To code required to include a bundle is very simple and compact:
 * \verbatim
!include( bundles/services/BuildingManager/BuildingManager.prf ) {
	message( "*****  No bundles/services/BuildingManager/BuildingManager.prf file found. SKIPPED. *****" )
} 
\endverbatim
 *
 * For convenience, when a bundle is included it will print a message, such as:
 * \verbatim
Project MESSAGE: WOSH - BUNDLES [Services] - BuildingManager
\endverbatim
 *
 * Bundles' source is located in <a href="../../src/bundles">/src/bundles</a> sub-folders, some
 * project files are provided in order to simplify inclusion and maintenance.
 * <a href="../../src/bundles/bundles.pro">/src/bundles/bundles.pro</a> will include:
 *  - /src/bundles/services/services.pri
 *  - /src/bundles/devices/devices.pri
 *
 * These files are not included in distribution because they define which bundles are included
 * for the local working-copy/application, in other words you should create and customize them
 * including the devices/services you need.
 *
 * For convenience two default project-files are provided and automatically included when the
 * custom files (listed previously) are missing:
 *  - <a href="../../src/bundles/services/services.pri.default">services.pri.default</a>
 *  - <a href="../../src/bundles/devices/devices.pri.default">devices.pri.default</a>
 *
 * These default project-files will include most stable bundles (and not requiring any external library).
 *
 * It may look complex, but in fact, building WOSH is easy as executing few commands.
 *
 * Go to your platform's section to generate Makefile for your preferred IDE.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_3rdparty 3rd-party Libraries
 * 
 * Some parts of the WOSH Framework (or built-in services) may be based on
 * external (3rd-party) libraries. WOSH Core doesn't require any of these libs.
 * Whenever it is possible and reasonable, these libraries are provided with
 * source/full distribution.
 * WOSH will use only state-of-the-art libraries, open source and distributed
 * with a compatible license.
 *
 * External libraries are placed in <a href="../../lib/3rdparty">/lib/3rdparty</a>
 * folder. It is organized as following:
 *  - /lib/3rdparty contains \c compiled libraries (.lib, .a files)
 *  - each library has its own sub-folder. It may contain a single README file,
 *    but also source code (i.e. when it was locally updated) and custom data
 *
 * When for any reason, some files (such as configuration) of the external
 * library have been modified (to work with WOSH), these files are provided (as its README).
 *
 * Here is the list of 3rd-party libraries grouped by framework namespace:
 *  - AI [wosh::ai]
 *    - \b galib [247] (ANSI C++, multiplatform)
 *
 *  - Persistence [wosh::persistence]
 *    - Nokia \b QT4 [QtXml] (ANSI C++, multiplatform)
 *    - \b libxml2 (ANSI C++, multiplatform)
 *
 *  - Networking [wosh::network]
 *    - Nokia \b QT4 [QtNetwork] (ANSI C++, multiplatform)
 *    - \b libSockets (ANSI C++, multiplatform)
 *    - \b libcurl (ANSI C++, multiplatform)
 *
 * Here is the list of 3rd-party libraries grouped by bundle:
 *  - wosh::devices::JabberGlooxBundle
 *    - \b libgloox (ANSI C++, multiplatform)
 *
 *  - wosh::services::FestivalBundle
 *    - \b libfestival (POSIX only)
 *
 * As said previously, a minimal WOSH built doesn't require any of these libraries.
 * 
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_compile_posix Build on Linux (POSIX)
 *
 * Indeed you need built-tools such as GCC (required 3.x, suggested 4.x), and STL
 * as supported by <i>GNU Standard C++ Library v3 (libstdc++-v3)</i> or later.
 *
 * On Debian-based distributions, such as Ubuntu, you may install them as easy as executing:
 * \verbatim
alex@linbox:/$ sudo apt-get build-essential
\endverbatim
 *
 * QT is available in most Linux distributions, on Debian-based systems you may install it executing:
 * \verbatim
alex@linbox:/$ sudo apt-get install libqt4-dev libqt4-network
\endverbatim
 * these packages may require some more packages (accept all of them),
 * as developer you may install also \c libqt4-dbg module.
 *
 * To ensure the requirements are fulfilled, check response of following commands:
 * \verbatim
alex@linbox:/$ which qmake
  /usr/bin/qmake
alex@linbox:/$ qmake --version
  QMake version 2.01a
  Using Qt version 4.4.3 in /usr/lib
\endverbatim
 *
 * Once ready, in order to create Makefile, you need to execute in the project base directory :
 * \verbatim
alex@linbox:/home/alex/WOSH/src$ qmake <PROJECT>.pro
\endverbatim
 * You probably want to build \c woshsrv.pro
 * This operation is required only once, even after updating qmake project files.
 *
 * On my main WOSH server (Debian Lenny) it looks like <a href="../../var/log/qmake.woshsrv.log">/var/log/qmake.woshsrv.log</a>.
 *  
 * The Makefile has been created and you may build the software as usual, executing:
 * \verbatim
alex@linbox:/home/alex/WOSH/src$ make
\endverbatim
 *
 * When switching to another WOSH Application in the same path (as building woshshop.pro after woshsrv.pro),
 * it is suggested to clean the temporary files, executing standard \c clean option:
 * \verbatim
C:\WOSH\src> make clean
\endverbatim
 *
 * Any raised error is probably related to 3rd-party libraries (or their paths)
 * which may be mis-configured or missing on your system, such libraries may be
 * required by included bundles, as said in \c overview section.
 * Don't worry, WOSH compiles properly once environment is ready.
 *
 * Example of required libraries by \b woshsrv (with many services ) running on Debian Lenny is
 * <a href=".../../var/log/dependences.woshsrv.posix.ldd">/var/log/dependences.woshsrv.posix.ldd</a> ( \c ldd output).
 *
 * You may build other applications (such as \ref page_applications_woshshop "woshshop",
 * \ref page_applications_woshremote "woshremote" ) in the same way.
 *
 * \note \c "make install" is not provided yet.
 *
 * Output will be generated in <a href="../../bin">/bin</a> folder (such as 'woshsrv').
 *
 * Built!? Now you may read \ref page_run page.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_compile_win32 Build on Windows (32/64) [native]
 *
 * WOSH may be compiled on Windows systems in two ways: \b native, \b ported (mingw).
 * See \ref page_build_compile_win32_mingw "Win32-MinGW section".
 *
 * Official binaries of WOSH applications are built native.
 *
 * On Windows, QT and WOSH support Microsoft Visual Studio 2005-2008 (also Express edition).
 *
 * \warning
 *  Download QT source code and build it following instructions, it's very easy but takes about 2 hours of processing.
 *  Take care when selecting the archive on QT website, it may be confusing: you need QT's source code. Actually the package name
 *  is: <a href="http://qt.nokia.com/downloads/windows-cpp-vs2008">Qt for Open Source C++ development on Windows (VS2008)</a>
 *  (\c qt-win-opensource-4.6.1-vs2008.exe )
 *  Note: It's a very good thing to avoid spaces in the QT's installation path.
 *
 * \see http://doc.qt.nokia.com/install-win.html
 * When using VS2008, commands are:
 * \verbatim
C:\dev\QT\4.6.1> configure -platform win32-msvc2008
C:\dev\QT\4.6.1> nmake
\endverbatim
 *
 * Once QT is built, you can continue:
 *
 * Some (BATCH) scripts are provided in order to automate the creation of Visual Studio projects (solutions)
 * but you have to setup a custom \c "Windows Environment variable" used by the script to locate QT installation.
 * You may configure such variables in: My Computer->Properties->Advanced->Environment variables->System Variable
 *
 *  - QTDIR_WIN32 set to the root path of QT - native (locally built with MSVC)
 *
 * Provided scripts are:
 *  - <a href="../../build/mscv_make_apps.bat">/build/mscv_make_apps.bat</a>
 *    Create project files and/or build solution of WOSH Applications (woshsrv, woshshop, woshremote, woshkiosk)
 *
 *  - <a href="../../build/mscv_make_lib.bat">/build/mscv_make_lib.bat</a>
 *    Create project files and/or build solution of WOSH Library (standalone library)
 *
 *  - <a href="../../build/msvc_make_3rdparty.bat">/build/msvc_make_3rdparty.bat</a>
 *    Build 3rd-party libraries (requirements depends on built-setting)
 *
 * You are probably interested into WOSH Applications (double-click \c mscv_make_apps.bat).
 *
 * Manual generation of \c Makefile looks like:
 * \verbatim
C:\WOSH\src> qmake woshsrv.pro -t vcapp
\endverbatim
 *
 * Once the project has been created (as woshsrv.vcproj, woshshop.vcproj, woshremote.vcproj in \c /src folder),
 * you may open Microsoft Visual Studio and build the project (the solution file will be generated by VS itself).
 *
 * \note Depending on your system, you may need to customize some fields, such as:
 *  "C++| Code Generation" and set "Runtime Library" to "Multithreaded (Debug) DLL", "Linker tabsheet"
 *  Open its last page where it says "command line" set to /FORCE:multiple
 *
 * Built!? Now you may read \ref page_run page.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_compile_win32_mingw Build on Windows (32/64) [MinGW]
 *
 * Since mingw-building is the most common option for QT-win and it's almost like
 * building software on Linux, the building process is very easy.
 * Reference download are (any of these):
 *  - http://qt.nokia.com/downloads/sdk-windows-cpp
 *  - http://qt.nokia.com/downloads/windows-cpp
 *
 * As any QT application, you should open the QT Command Prompt (it may be found in
 * QT's start menu), change to WOSH \c src folder and generate the Makefile:
 * \verbatim
C:\WOSH\src> qmake woshsrv.pro
\endverbatim
 * Once the \c Makefile has been created (in \c /src folder), you may build the application executing:
 * \verbatim
C:\WOSH\src> mingw32-make
\endverbatim
 *
 * When switching to another WOSH Application in the same path (as building woshshop.pro after woshsrv.pro),
 * it is suggested to clean the temporary files, executing standard \c clean option:
 * \verbatim
C:\WOSH\src> mingw32-make clean
\endverbatim
 *
 * A (BATCH) script is provided in order to automate the building,
 * but you have to setup a custom \c "Windows Environment variable" used by the script to locate QT installation.
 * You may configure such variables in: My Computer->Properties->Advanced->Environment variables->System Variable
 *
 *  - QTDIR_WINGW set to the root path of QT - MinGW (included in the most common versions of QT)
 *
 * Provided scripts is:
 *  - <a href="../../build/mingw_make_apps.bat">/build/mingw_make_apps.bat</a>
 *    Create Makefiles and and/or build WOSH Applications (woshsrv, woshshop, woshremote, woshkiosk)
 *
 * You just need to execute (double-click) the script in the \c build folder.
 *
 * Built!? Now you may read \ref page_run page.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_compile_wince Build on Windows CE/Mobile
 *
 * WOSH Core and most of the framework is compatible with Windows CE/Mobile 6.0
 * The goal of \ref page_applications_woshcesrv "woshcesrv" is to provide some Mobile-services
 * to the WOSH network: such as messaging (SMS) and call monitoring.
 * The hardware device must be connected to the local network,
 * I run WOSH CE Server on my Samsung smartphone, USB connected to Linux (RNDIS).
 *
 * WOSH CE Server is a minimal server intended to host the wosh::devices::WindowsMobileBundle only.
 *
 * \warning
 *  You should be familiar with Windows CE/Mobile devices and development.
 *  You need to install and configure Windows Mobile 6.0 SDK, Microsoft ActiveSynch.
 *  You must be able (using ActiveSynch) to browse device's filesystem and a PAN network
 *  must be enabled (should be done automatically).
 *  If you are not familiar with Mobile/CE devices, search for a tutorial
 *  and test any simpler applications before building and running WOSH.
 *
 * However, requirements of Windows CE/Mobile built are few:
 *  - Microsoft Visual Studio 2005-2008 (8.0,9.0) [or Express edition]
 *  - Microsoft Windows Mobile 6.0 SDK
 *  - QT 4.1 (or later) built (locally, on your PC) for Windows CE/Mobile
 *
 * You may download the Windows Mobile 6.0 SDK and Visual Studio C++ Express
 * freely from Microsoft website.
 *
 * \warning
 *  You need to install (and compile) QT SDK for Windows CE, it's very easy but takes about 2 hours of processing.
 *  Download QT source code and build it following instructions. Take care when selecting the
 *  archive on QT website, it may be confusing: you need QT's source code. Actually the package name
 *  is: <a href="http://qt.nokia.com/downloads/win-ce-cpp">Qt libraries 4.6.1 for Windows CE (160 MB)</a>
 *  (\c qt-everywhere-opensource-src-4.6.1.zip  )
 *  Note: It's a very good thing to avoid spaces in the QT's installation path.
 *
 * My own QT installation's commands were:
 * \code
C:\dev\Qt\wince.4.6.1> set PATH=C:\dev\Qt\wince.4.6.1;%PATH%
C:\dev\Qt\wince.4.6.1> configure -platform win32-msvc2008 -xplatform wincewm60standard-msvc2008
C:\dev\Qt\wince.4.6.1> setcepaths wincewm60standard-msvc2008
C:\dev\Qt\wince.4.6.1> nmake
 * \endcode
 *
 * Once QT is built, you can continue:
 *
 * A (BATCH) script (<a href="../../build/msvc_make_woshcesrv.bat">/build/msvc_make_woshcesrv.bat</a>) is provided
 * in order to automate the creation of the Visual Studio project (solution),
 * but you have to setup a custom \c "Windows Environment variable" used by the script to locate QT installation.
 * Set QTDIR_WINCE to the root path of QT-native (locally built with MSVC), you may add the variable in:
 * My Computer->Properties->Advanced->Environment variables->System Variable
 *
 * You just need to execute (double-click) the script in the \c build folder.
 *
 * QT installation comes with a custom prompt (same as Visual Studio prompt, but adding some more environmental
 * settings. Manual generation of \c Makefile looks like:
 * \verbatim
C:\WOSH\src> qmake woshcesrv.pro -t vcapp
\endverbatim
 *
 * Once the project has been created (woshcesrv.vcproj in \c /src folder), you may open
 * Microsoft Visual Studio and build the project (the solution file will be generated).
 *
 * \note Depending on your system, you may need to reset the field: Project->Properties->Linker->Advanced->Entry Point
 *
 * Built!? Now you may read \ref page_run page.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_compile_macos Build on MAC OS
 *
 * \warning WOSH has NEVER been compiled neither tested on Mac OS, although it should work.
 *
 * \par Would help?
 *  Send results to contact _AT_ alessandropolo.name or on SourceForge website.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_build_doc Building Documentation
 *
 * The tool Doxygen (<a href="http://www.doxygen.org/index.html">http://www.doxygen.org</a>)
 * is required to build the documentation. 
 *
 * The complete WOSH documentation is integrated into source code and written in
 * doxygen format. This document (as others) is generated by DoxyGen.
 *
 * The current configuration also requires Dot/Graphwiz (http://www.graphviz.org/);
 * change <tt>HAVE_DOT = YES|NO</tt> in <a href="../../doc/Doxyfile">/doc/Doxyfile</a>.
 *
 * On Debian-based system, you may install required packages executing:
 * \verbatim
alex@linbox:/$ sudo apt-get install doxygen graphviz
\endverbatim
 *
 * To build documentation manually change to <a href="../../doc">/doc</a> folder and execute:
 * \verbatim
alex@linbox:/home/alex/WOSH/doc$ doxygen Doxyfile
\endverbatim
 *
 * Doxygen will generate documentation in sub-folders, by default HTML output only
 * is enabled (writing in \c /doc/html folder). The processing takes few minutes.
 *
 * You can give look to <tt>/doc/html/index.html</tt>.
 * 
 * On Windows system you may install Doxygen and open configuration file with \c doxywizard.
 *
 *
 ****************************************************************************
 *
 */
